20# The software was developed in the frame of contract 21398/08/NL/GLC with the European Space Agency (ESA). Technical Offer was Christoph Ernst.
21# Further features were developed under contract UPC-C7767 with Thales Alenia Space España (TAS-E).
22# \par
23# Contributions to the definition of the software functionality and testing have been made by
24# Christoph Ernst, Mónica Martínez Mendoza and other ESA-ESTEC personnel,
25# and Santiago Sobrino and Luis Roglá from TAS-E.
26#
27# \section theory_sec Synthesis of microwave lossy filters
28# See \ref theory_page for a brief introduction about synthesis of microwave lossy filters.
29#
30# \section license_sec License
31# See \ref license_page page.
32#
33# \section install Installation
34# See separate installation instructions in files README.txt, README.pdf or readme/html/README.html
35#
36# \section description Software description:
37# The LossyFilters software package has been written to synthesize filters following various forms of classical (no-loss considered in the synthesis), pre-distortion and prescribed insertion loss synthesis. This software obtains the coupling matrix of several network topologies for a given response and allows performing rotations on them to find the desired topology. Additionally, the software allows to evaluate the effect of loss in the networks resulting from the synthesis, even in those cases where the synthesis results in an ideal lossless network (i.e., classical and pre-distortion synthesis).
38#
39# The software package has been divided in two parts:
40#
41# - <B>Open-source GUI and free libraries:</B> The graphical user interface (GUI) MWfiltersGUI, the 'Free Filter Library' and the 'Common Functions Library' are free open-source software with capability to edit the input parameters, synthesize Butterwork, Chebyshev and Quasieliptic filters with minimum insertion loss, rotate and save the filter coupling matrix and display and save the [S] parameters. The GUI will also run the non-free libraries if they are installed in the system.
42#
43# - <B>Non-free libraries:</B> The non-free libraries are not required but, when they are installed in the system, allow the synthesis of Generalized Chebyshev filters with prescribed transmission zeros and linear phase optimization ("Library of Extra Filters") and the synthesis of lossy filters with the pre-distortion and prescribed insertion loss techniques ("Library of Lossy Filters).
44#
45# \subsection freefunc Functionality of the free GUI and libraries
46#
47# - The GUI is full-featured with complete functionality to open, edit, save and execute parameter files, as well as plot [S] parameters and manually edit coupling matrices:
48# - Actions can be launched by menus, toolbar buttons or keyboard shortcuts.
49# - There are tooltips in the parameters edit widgets.
50# - Application output in main window log widget and status bar.
51# - Modeless parameter edit dialog window with Accept / Compute / Discard buttons, to allow the computation with trial parameter values without closing the dialog.
52# - Preventive data validation at the parameters edit widgets in order to prevent the user introducing invalid data.
53# - Frequency parameters edit widgets allow the user to set THz, GHz, MHz, kHZ, Hz units.
54# - The parameter edit window detects if there are changes in the parameters, so that the application can warn the user if he is going to destroy non-saved changes.
55# - Plots S-parameters graph with phase or group delay in right-axis.
56# - Plots support adding, moving and deleting markers.
57# - Select which results to plot.
58# - Zoom S-parameter plot.
59# - Manual and autoscaling for each axis of S-parameter plot.
60# - Print S-parameter plot to printer or PDF file.
61# - Display coupling matrices and Q of resonators.
62# - Edit coupling matrix topology for non-zero elements optimization.
63# - Coupling matrices window: Manual rotation, node scaling, element anhilitation, add non-resonant nodes, edit matrix entries or Q values, file load/save, etc. There are facilities to undo and revert to any previous state.
64# - Plot S-parameters computed from the current coupling matrix compared with S-parameters computed from the characteristic polynomials. Display the average error in dB.
65# - Read [S] parameters from Touchstone format file.
66# - Store, recover and compare results from different computations or read from Touchstone format file.
67# - Specification mask read from file and plotted.
68# - Sensitivity analysis.
69# - User-selectable predistortion zeros.
70# - Code fully documented with Doxygen.
71#
72# - The free libraries have functionality to:
73# - Read and parse parameters file.
74# - Write parameters file.
75# - Printing strings to:
76# - Console, when called from the command line.
77# - Main window log widget, when called from the GUI.
78# - Catches syntax errors in the parameter file.
79# - Correctly handles non-ASCII characters. Reads and writes UTF-8 format parameter files, accepts non-English characters in the GUI and in console output. When python reports that an output device is not able to print non-ASCII characters, the console interface replaces 8-bit characters by "?" in the output.
80# - Filter synthesis: Butterworth, Chebyshev and Quasielpitic filters.
81# - Generation of transversal coupling matrix (TCM) N+2.
82# - Functions to generate rotation matrices and to find the angle that zeroes a given coupling matrix element.
83# - Transformation from transversal coupling matrix (TCM) to folded coupling matrix (FCM) and to many other types of coupling matrices.
84# - Calculation of the passband coupling matrix, which is obtained from the low-pass one by a scaling. The resulting passband coupling matrix can be directly related to design parameters used for the filter design, such as the coupling between resonators.
85# - Optimize coupling matrix elements for a given topology and resonator Q, adjusting [S] parameters to the polynomials [S] parameters or to a specification mask.
86# - Prescribed flatness for lossless-like filters with flat passband response. The quality factor of a filter to emulate is specified in order to append additional resonator losses.
87# - Displays Q of resonators.
88# - Compute energy stored at resonators and reactive couplings and power dissipated at resonators and resistive couplings.
89# - Reports roundoff errors in polynomial roots and partial fraction expansion.
90# - Reports error in S-parameters computed from transversal and folded coupling matrices compared with S-parameters computed from the characteristic polynomials.
91# - Code fully documented with Doxygen.
92#
93# \subsection nonfreefunc Functionality of the non-free libraries
94#
95# - The <B>"Library of Extra filters"</B> provides the following additional functions:
96# - Generalized Chebyshev transfer function with arbitrary transmission zeros [from Cameron, chapter 6].
97# - Linear phase equalization, optimizing the position of real and/or complex transmission zeros.
98# - Code fully documented with Doxygen.
99#
100# - The <B>"Library of Lossy filters"</B> provides the following additional functions:
101# - Filter losses: predistortion (conventional or adaptive).
102# - Filter losses: "Prescribed insertion loss" with non-Uniform Q case 1 (k21+k11+k22 asymmetrical), case 2 (k21) and case 3 (k21+zero/pole).
103# - FCM matrix rotation to obtain uniform Q in resonators for Lossy Filter case-1 (kS11 + kS21), N=4 and N=6 and case-3 (kS21 + pole/zero), N=6. Automatic symmetrization of transmission zeros if necessary.
112# The lossyfilters software package described below, including an open-source GUI, free libraries and non-free
113# libraries is owned by UPC and is protected by the applicable copyright laws and international treaty
114# provisions.
115#
116# This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
117# without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
118# This program is distributed as is and with all possible imperfections
119# and faults. UPC does not warrant neither that the operation of this program will be uninterrupted
120# nor that it is error free. In no event shall UPC be liable for any responsibilities
121# arising out of the use or inability to use this program or the documentation.
122#
123# \section sec_licfree Open-source GUI and libraries
124#
125# The graphical user interface (GUI) mwfiltersgui.py and its associated files, the 'Free Filter Library'
126# libfreefilters.py and the 'Common Functions Library' libcommonfunc.py are free open-source software released
127# under the GNU General Public License (GPL) version 3.
128#
129# You can redistribute it and/or modify it under the terms of the GNU GPL as published by the Free Software
130# Foundation; either version 3 of the License, or (at your option) any later version. See the GNU GPL for more
131# details. You should have received a copy of the GNU GPL along with this program in file "LICENSE.GPL3" or file
132# "LICENSE.txt"; if not, download it from http://www.gnu.org/licenses/gpl-3.0.html .
133#
134# \par
135# Additional permission under GNU GPL version 3 section 7:
136#
137# \par
138# If you modify this Program, or any covered work, by linking or combining it with the "Extra Filters Library"
139# (libextrafilters), the "Lossy Filters Library" (liblossyfilters) or the "License Check Library"
140# (libchecklicense), or modified versions of that libraries, containing parts covered by the terms described in
141# files LICENSE.LIBEXTRAFILTERS and LICENSE.LIBLOSSYFILTERS, the licensors of this Program grant you additional
142# permission to convey the resulting work.
143#
144# Lossyfilters software GUI uses the open-source dbplot.py module, which is based in part on the work of the Qwt
145# project (http://qwt.sf.net) and has been released by UPC under the terms of the GNU GPL version 3.
146#
147# \section sec_lic_nonfree Non-free libraries
148#
149# The "Extra Filters Library" and the "Lossy Filters Library" are not free software and need a user license from
150# UPC. The European Space Agency (ESA) has such user license with right to use and modify the present version and
151# future updates of these libraries and to make copies of these libraries for use in multiple computers and for
152# backup or archival purposes.
153#
154# - "Extra Filters Library" for the computation of generalized Chebyshev filter characteristic polynomials is
155# distributed by UPC either in the source file "libextrafilters.py", the corresponding bytecode file
156# "libextrafilters.pyc" or bound into a binary executable file. License terms are described in the
157# LICENSE.LIBEXTRAFILTERS file.
158# - "Lossy Filters Library" for the computation of characteristic polynomials including filter losses is
159# distributed by UPC either in the source file "liblossyfilters.py", the corresponding bytecode file
160# "liblossyfilters.pyc" or bound into a binary executable file. License terms are described in the
161# LICENSE.LIBLOSSYFILTERS file.
162# - The "Extra Filters Library" and the "Lossy Filters Library" need the "License Check Library", which
163# distributed toghether with them either in the executable Python bytecode file "libchecklicense.pyc" or bound
164# into a binary executable file. The source file "libchecklicense.py" is not distributed. The "License Check
165# Library" has been developed by UPC for checking the user's license to run software released by the AntennaLab
166# research group at the Department of Signal Theory and Communications (TSC). The "License Check Library" is
167# distributed and licensed by UPC under the same terms as the "Extra Filters Library" and the "Lossy Filters
168# Library", with the following additional restrictions:
169# - The source code is not distributed.
170# - It is specially forbidden to modify the "License Check Library" source or binary code.
171# - It is also forbidden to reverse engineer, decompile, or disassemble the "License Check Library" with the
172# intent to violate license agreement of the "Extra Filters Library" or the "Lossy Filters Library".
173#
174# \page theory_page Synthesis of microwave lossy filters
175#
176# The project goals at large are to investigate novel lossy filter synthesis techniques to obtain filters whose insertion loss flatness can be made equal to that of an (ideal) lossless filter, despite the limited Q of the resonators within the filter.
177#
178# The classical synthesis procedure consists on obtaining a purely reactive (no dissipation effect) network that defines the resonant frequency of the resonators forming the filter and the way they are coupled. However, in practice, some dissipation always exist in the final filter implementation which can be evaluated afterwards by introducing the material losses (finite Q of the resonators) into the synthesized lossless network.
179#
180# Among other effects, this approach leads to filters with minimum insertion loss in the passband at one frequency at the expense of additional passband rounding towards the band-edges, being the use of high Q resonators the only way to achieve filters with flat pass-band response by means of classical synthesis techniques. This may result in heavy and large filters which might be impractical in space systems, or in wireless and handset components with strong demand for low-cost and small size.
181#
182# This can be overcome by the use of non standard filter synthesis techniques such as:
183#
184# - <B>Pre-distortion synthesis:</B> synthesizes a lossless network whose pole placement is such that, after introducing the losses, produces the desired (improved) in-band flatness. However, this is at the expense of increased in-band signal reflections.
185# \par
186# R. J. Cameron, C. M. Kudsia, R.R. Mansour, Microwave Filters for Communication systems.
187# Fundamentals, Design, and applications, John Wiley & Sons, 2007. Dissipation I movement de sigma
188# \par
189# Ming Yu et al., "Predistortion Technique for Cross-Coupled Filters and its application to satellite communication systems",
190# IEEE MTT-51, pp. 2505-2515, Nov. 2003
191#
192# - <B>Prescribed insertion loss synthesis:</B> In order to obtain both good insertion loss flatness and good return loss, the insertion loss flatness is obtained at the expense of an increase of the overall insertion loss, therefore the resulting filters are of use in those applications where the filters are placed after the low noise amplifier without affecting the noise figure, as it occurs in input multiplexers (IMUX) for satellite transponders.
193# \par
194# V. Miraftab, Ming Yu, "Advanced Coupling Matrix and Admittance Function Synthesis Techniques for Dissipative Microwave Filters," Microwave Theory and Techniques, IEEE Transactions on , vol.57, no.10, pp.2429-2438, Oct. 2009.
195# \par
196# I. C. Hunter, A. Guyette, and R. D. Pollard, "Passive Microwave Receive Filter Network Using Low-Q Resonators", IEEE microwave Magazine, September 2005.
197# \par
198# A.C. Guyette, I. C. Hunter, R. Pollard, "The design of microwave bandpass filters using resonators with nonuniform Q", IEEE MTT-54 (11), November 2006, pp.3914-3922.
199#
200# Using these lossy filters synthesis techniques, very low resonator Q that can be employed and, therefore, low cost and compact filters (such as microstrip filters) can be realized.
201#
202# \section ref_sec References:
203#
204# The main references to the work in this project are:
205# \par
206#J.Mateu, C. Collado, J.M. O'Callaghan, <br>
207#"Lossy Filter Synthesis and Study of Topology Solution Space", <br>
208#<i>ESA working paper 2366</i>. TEC-ETM/2009.142/CE. First issued: September 2008.
209# \par
210#J. Mateu, A. Padilla, C. Collado, M. Martinez-Mendoza, E. Rocas, C. Ernst, J M. O’Callaghan, <br>
211#"Synthesis of 4th order Lossy Filters with uniform Q distribution", <br>
